@
目录什么是 Swagger？依赖引入springfox引入方式knife4j引入方式引入美化bootstrap-UI详细配置swagger资源访问路径加入白名单访问路径：小技巧：相关内容地址Swagger官方文档https://swagger.io/docs/specification/2-0/basic-structure/Swagger常用注解https://blog.csdn.net/weixin_42526326/article/details/119824857Swagger2常用注解https://blog.csdn.net/weixin_42526326/article/details/119963866Swagger3常用注解https://blog.csdn.net/weixin_42526326/article/details/119965092什么是 Swagger？Swagger是一组围绕 OpenAPI 规范构建的开源工具，可帮助您设计、构建、记录和使用 REST API。主要的 Swagger 工具包括：
Swagger Editor – 基于浏览器的编辑器，您可以在其中编写 OpenAPI 规范。Swagger UI – 将 OpenAPI 规范呈现为交互式 API 文档。
swagger2于17年停止维护，现在最新的版本为 Swagger3（Open Api3）。
依赖引入我们可以去 mvnrepository（maven中央仓库） 搜索版本，但是建议不要用最新版
springfox引入方式io.springfoxspringfox-boot-starter3.0.0knife4j引入方式com.github.xiaoyminknife4j-spring-boot-starter3.0.3引入美化bootstrap-UIcom.github.xiaoyminswagger-bootstrap-ui1.8.5详细配置配置文件加上@EnableOpenApi、@Configuration 会自动开启配置，启动类不需要加任何注解
package com.doctorcloud.pc.interceptor.config;import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;import io.swagger.annotations.ApiOperation;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.context.annotation.Profile;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.oas.annotations.EnableOpenApi;import springfox.documentation.service.*;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spi.service.contexts.SecurityContext;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;import java.util.ArrayList;import java.util.HashSet;import java.util.List;import java.util.Set;/** * * @author*/@Configuration@Profile({"dev","local"})@EnableOpenApi@EnableSwaggerBootstrapUIpublic class SwaggerConfig {/** * 是否开启swagger配置，生产环境需关闭 *//*@Value("${swagger.enabled}")*/private boolean enable;/** * 创建API * http:IP:端口号/swagger-ui/index.html 原生地址 * http:IP:端口号/doc.html bootStrap-UI地址 */@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.OAS_30).pathMapping("/")// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）/*.enable(enable)*/.apiInfo(apiInfo())// 设置哪些接口暴露给Swagger展示.select()// 扫描所有有注解的api，用这种方式更灵活.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 扫描指定包中的swagger注解// .apis(RequestHandlerSelectors.basePackage("com.doctorcloud.product.web.controller"))// 扫描所有 .apis(RequestHandlerSelectors.any()).paths(PathSelectors.regex("(?!/ApiError.*).*")).paths(PathSelectors.any()).build()// 支持的通讯协议集合.protocols(newHashSet("https", "http")).securitySchemes(securitySchemes()).securityContexts(securityContexts());}/** * 支持的通讯协议集合 * @param type1 * @param type2 * @return */private Set newHashSet(String type1, String type2){Set set = new HashSet();set.add(type1);set.add(type2);return set;}/** * 认证的安全上下文 */private List securitySchemes() {List securitySchemes = new ArrayList();securitySchemes.add(new ApiKey("token", "token", "header"));return securitySchemes;}/** * 授权信息全局应用 */private List securityContexts() {List securityContexts = new ArrayList();securityContexts.add(SecurityContext.builder().securityReferences(defaultAuth()).forPaths(PathSelectors.any()).build());return securityContexts;}private List defaultAuth() {AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];authorizationScopes[0] = authorizationScope;List securityReferences = new ArrayList();securityReferences.add(new SecurityReference("Authorization", authorizationScopes));return securityReferences;}/** * 添加摘要信息 */private ApiInfo apiInfo() {// 用ApiInfoBuilder进行定制return new ApiInfoBuilder()// 设置标题.title("接口文档")// 描述.description("描述")// 作者信息.contact(new Contact("doctorCloud", null, null))// 版本.version("版本号:V.1")//协议.license("The Apache License")//协议url.licenseUrl("http://www.baidu.com").build();}}swagger资源访问路径加入白名单- /swagger-ui/**- /webjars/**- /doc.html- /swagger-resources/**- /v3/**访问路径：http:IP:端口号/swagger-ui/index.html 原生地址http:IP:端口号/doc.html bootStrap-UI地址小技巧：不建议使用swagger原生页面设置权限，建议使用doc页面设置token，搜索接口更方便(主要是好看)
之前有用swagger3，突然间接口文档出参都显示不了，不得已只得退回到swagger